Inside Macintosh: Open Transport /

Chapter 2 - Providers / Providers Reference

Functions / Controlling a Provider's Mode of Operation

OTAckSends

Specifies that a provider make an internal copy of data being sent and that it notify you when it has finished sending data.

C INTERFACE

OSStatus OTAckSends(ProviderRef ref);

C++ INTERFACE

OSStatus TProvider::AckSends();

PARAMETERS

ref

The provider reference of the provider that is sending data.

DESCRIPTION

By default, providers make an internal copy of data before sending it and they do not acknowledge sends. If you use the OTAckSends function to specify that the provider acknowledge sends and you call a function that sends data, the provider does not copy the data before sending it. Instead, it reads data directly from your buffer while sending. For this reason, you must not change the contents of your buffer until the provider is no longer using it. The provider lets you know that it has finished using the buffer by calling your notifier function and passing T_MEMORYRELEASED event code for the code parameter, a pointer to the buffer that was sent in the cookie parameter, and the size of the buffer in the result parameter.

If you have not installed a notifier function for the provider, this function returns the kOTAccessErr result.

If a send is currently outstanding on the provider, from a call to the OTSnd, OTSndUData, OTSndUReply, OTSndURequest, OTSndReply, or OTSndrequest function, the OTAckSends function returns a kOTChangeStateErr message.

WARNING

You need to be sure that are no outstanding T_MEMORY_RELEASED events for a provider before you close the provider. Otherwise, Open Transport attempts to deliver the event to a provider that no longer exists, with unpredictable results, such as crashing the system.

SPECIAL CONSIDERATIONS

Do not wait for a T_MEMORYRELEASED event from a previous send operation to trigger more sends. When a T_MEMORYRELEASED event occurs depends on how the underlying provider is implemented. It may hold on to memory until the next send occurs, or have some other functionality which causes it to delay releasing memory.

SEE ALSO

To request that the provider copy the data before sending it, use the OTDontAckSends function, described in the next section.

To find out a provider's current send-acknowledgment status, call the OTIsAckingSends function (page 2-38).

For additional information, see "Setting a Provider's Send-Acknowledgment Status" on page 2-10.

The send-acknowledgment status of a provider is ignored by mapper providers, AppleTalk providers, and TCP/IP providers. For information about how endpoint providers are affected, see the discussion of an endpoint's mode of operation in the chapter "Endpoints" in this book.